home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / TURB_VIS / TVDMX / CHANGES.DOC next >
Text File  |  1994-06-20  |  13KB  |  374 lines
  1.  
  2.     tvDMX has had several changes from version 1.0 through 2.5.
  3.     Not all of the documentation has been updated, but these notes
  4.     cover the most prominent changes.
  5.  
  6.  
  7. FORMSHOP DEMO
  8. ═════════════
  9.  
  10.   Previous versions of FORMSHOP.PAS did not always compile with BP7
  11.   because BP7's capacity for generating recursive NewSItems in single
  12.   statements was limited.
  13.  
  14.   This was remedied by splitting NewSItem lists into several functions.
  15.   See FORMSHOP.PAS if you have large forms.
  16.  
  17.  
  18. RECORD and FIELD SELECTION
  19. ══════════════════════════
  20.  
  21.   As described in the other documentation files, the TDmxEditor's
  22.   RecordSelected and FieldSelected fields indicate whether a record or
  23.   field is selected and highlighted.  In the past, both the record and
  24.   field have always been selected while the view's state was sfFocused
  25.   (except during field and record movement, or while changing size).
  26.  
  27.   Selection status is now determined by the sfActive and sfSelected
  28.   states.  This allows a record to be selected, when a field is not.
  29.   In an active window with several views, the current record will stay
  30.   selected even when the field is deselected (via EvaluateField) as the
  31.   user tabs to the next view.  EvaluateRecord is only called when the
  32.   sfActive state changes; the view size changes; or the cursor moves up
  33.   or down.
  34.  
  35.   Remember: The SetupRecord, SetupField, EvaluateField and EvaluateRecord
  36.   methods are called internally.  You may intercept them by overriding
  37.   these virtual methods (provided that they call the inherited methods),
  38.   but your program should not call them directly.
  39.  
  40.   It should be noted here that most programmers will not be affected by
  41.   this change.
  42.  
  43.  
  44. FIELD HIGHLIGHTING
  45. ══════════════════
  46.  
  47.   After making the preceding change, it was then reasonable to highlight
  48.   the current field position after the field itself becomes deselected.
  49.   This might be desirable in a window with several selectable views.
  50.  
  51.   You can now accomplish this by setting:
  52.  
  53.     ShowFmt := ShowFmt + [showCurrentField];
  54.  
  55.   showCurrentField is defined in DMXGIZMA.PAS; and ShowFmt is a field of
  56.   object TDmxScroller in tvDMX.PAS.
  57.  
  58.  
  59. FUNCTION ENTRYBOX()
  60. ═══════════════════
  61.  
  62.   The concept of Turbo Vision's MessageBox and InputBox functions has
  63.   inspired a form-like version in the DMXFORMS.PAS unit.
  64.  
  65.       function EntryBox(Title: string;        // dialog box title
  66.             AData: pointer;        // form's data
  67.             AOptions: word;        // mfXXXX codes
  68.             AForm: PSItem        // form template list
  69.             ) : word;        // dialog box result
  70.  
  71.   Example:
  72.  
  73.       procedure EditEntryBox;
  74.       var  Code: integer;
  75.       begin
  76.     Code := EntryBox('Entry Box', @DataRec, mfOKCancel or mfDefault,
  77.             NewSItem('',
  78.             NewSItem('~    Name~',
  79.             NewSItem( '   \sssssssssssssssssssssssss',
  80.             NewSItem('',
  81.             NewSItem('~    SSN:    ~\###-##-####',
  82.             NewSItem('',
  83.             NewSItem('~    Balance:~\($rrr,rrr.zz)',
  84.             NewSItem('',
  85.                 nil))))))))
  86.         );
  87.     If (Code = cmOK) then ProcessDataRec;
  88.       end;
  89.  
  90.   The example creates a dialog box with OK and Cancel buttons, using
  91.   data from a record called DataRec.
  92.  
  93.   Many rows and fields can be added, making the window as elaborate as
  94.   required.  Scroll-bars will be added to the window if its height or
  95.   width are too large for the template design.
  96.  
  97.   New EntryBox options:
  98.  
  99.     mfHelpButton = $0004;    // adds a "Help" button, with cmHelp
  100.     mfViewOnly   = $0008;    // for viewing data only; no user entry
  101.     mfDefault    = $0010;    // makes OK button the cmDefault command
  102.  
  103.   Any mfXXXX button code (from MSGBOX.PAS) may be used to add buttons
  104.   to EntryBox, but the title codes (eg: mfError, mfInformation, etc.)
  105.   are not needed --and would conflict with new EntryBox options.
  106.  
  107.   The EntryBox procedure itself is fairly small.  Most of the work is
  108.   done by procedure MakeEntryBox.  This is important in that MakeEntryBox
  109.   may also to design special entry boxes using descendants of TDialog.
  110.  
  111.  
  112.  
  113.     These are the primary changes from version 1.x to 2.0.
  114.  
  115.  
  116. UNIT tvDMXBUF RECORD NUMBERS
  117. ════════════════════════════
  118.  
  119.   Function SeekRec() in unit tvDMXBUF uses a LONGINT value as a parameter,
  120.   where it had previously used an INTEGER.  This still needs more work
  121.   before it can be extended to long databases.  Look for updates in a
  122.   future version.
  123.  
  124.  
  125. REAL NUMBER FORMATS
  126. ═══════════════════
  127.  
  128.   tvDMX real numbers were originally displayed with trailing zeroes, eg:
  129.   'rrr,rrr.rrr' could format 10000 as ' 10,000.000'.  This has been changed
  130.   to make trailing zeroes optional, eg: ' 10,000    '.
  131.  
  132.   You can still display trailing zeroes using the 'Z' template codes, eg:
  133.   'rrr,rrr.zzz'.
  134.  
  135.  
  136. FORM-STYLE DATA ENTRY
  137. ═════════════════════
  138.  
  139.   The new TDmxForm object uses templates to create forms, just like its
  140.   parent, but it gets the templates in a list of strings, like this:
  141.  
  142.     Templates :=
  143.     NewSItem ('~    Data Entry Form~',
  144.     NewSItem ('',
  145.     NewSItem ('~Name: ~\ SSSSSSSSSSSSSSSSSS\~Age:~\WWW',
  146.     NewSItem ('~Balance:~\($rrr,rrr.zz)\~    APR:~\WZW%',
  147.     NewSItem ('',
  148.     NewSItem ('~     SSN:~\###-##-####',
  149.         nil))))));
  150.  
  151.   And this is the record type defined by those templates:
  152.  
  153.     TRecordType      =  RECORD
  154.     Name    :  string [18];
  155.     Age    :  word;
  156.     Balance    :  real;
  157.     APR    :  word;
  158.     SSN    :  string [9];
  159.     end;
  160.  
  161.   Tilde symbols ('~') mark off string-literals;  backslashes ('\') are
  162.   separate fields;  and everything else defines the field.  Naturally, you
  163.   need to be careful about marking these properly, but it's fairly easy.
  164.  
  165.   If your view had scrollbars, you can create huge scrollable data windows.
  166.  
  167. CREATING EXTRA-LONG TEMPLATES
  168. ══════════════════════════════
  169.  
  170.     Before now, record templates wider than 255 characters could only
  171.     be created by overriding the InitStruct() method.  This effort was
  172.     always complicated, and usually application-specific.
  173.  
  174.     Two new functions (in unit DMXGIZMA) provide two easy ways to extend
  175.     a template string:
  176.  
  177.  
  178.   function InitAppendFields (ATemplate : pstring) : DmxIDstr;
  179.     (*type DmxIDstr is a seven-character string)
  180.  
  181.     Example:
  182.  
  183.       const
  184.       TT : string [xx] = ' ssssssssssssss|wwww|wwww|';
  185.       T2 : string [xx] = ' wwww|wwww|sssssssssssssss|[x]|';
  186.  
  187.       begin
  188.     TT := TT + InitAppendFields (@T2);
  189.     ...
  190.  
  191.     InitAppendFields() creates a seven-byte string that contains a
  192.     control code which indicates to tvDMX that a pointer to another
  193.     template string is following.  Very long template codes can be
  194.     created by concatenating these strings, eg:
  195.  
  196.     TT := TT + InitAppendFields (@T2) + InitAppendFields (@T3);
  197.  
  198.     Extremely long template codes can be created by nesting.
  199.  
  200.     T3 := T3 + InitAppendFields (@T4);
  201.     T2 := T2 + InitAppendFields (@T3);
  202.     TT := TT + InitAppendFields (@T2);
  203.  
  204.     TT can then be used as your tvDMX template string.
  205.  
  206.  
  207.  
  208.   function InitTSItemFields (ATemplates : PSItem) : DmxIDstr;
  209.  
  210.     This function initializes a chain of TSItem templates, which will be
  211.     interpreted as one long tvDMX template chain.
  212.  
  213.     Example:
  214.  
  215.     TT := ' sssssssssssssss|WW,WWW |'
  216.         + InitTSItemFields (NewSItem (' sssssssssss`sssssssss|',
  217.                     NewSItem ('($rrr,rrr.rr)|',
  218.                     NewSItem (' CCCCC|WWW,WWW |',
  219.                     nil))))
  220.  
  221.     TT can then be used as your tvDMX template string.  It is much easier
  222.     to use function InitTSItemFields() than InitAppendFields().
  223.  
  224. ENUMERATED FIELDS
  225. ═════════════════
  226.  
  227.     Enum fields are byte fields that restricts the user to several
  228.     choices.  They use the NewSItem() function from the OBJECTS unit
  229.     to construct the list which is passed to tvDMX in the form of a
  230.     DmxIDstr (which is a seven character string) that is created by
  231.     this function (in unit DMXGIZMA):
  232.  
  233.       function  InitEnumField (ShowZ : boolean; AccMode,Default : byte;
  234.                    AItems : PSItem) : DmxIDstr;
  235.  
  236.     ShowZ specifies whether ShowZeroes should be set for this field;
  237.     AccMode is the field's access mode (accSkip, accReadOnly, etc.);
  238.     Default is the field's default value (normally zero).
  239.  
  240.     Example:
  241.  
  242.     TT := T1 + InitEnumField (FALSE, 0,0,
  243.             NewSItem (' Zero',
  244.             NewSItem (' One',
  245.             NewSItem (' Two',
  246.             NewSItem (' Three',
  247.             NewSItem (' Four',
  248.                  nil)))))
  249.                 );
  250.  
  251.     Important:  The TSItem list is disposed by tvDMX when the view is
  252.     disposed.  You should call InitEnumField() to create the list each
  253.     time that the view is created.  And please note that enum fields
  254.     are still in the experimental stage.
  255.  
  256.     The following procedures and functions (in DMXGIZMA) were written to
  257.     work with TSItem lists:
  258.  
  259.  
  260.       procedure DisposeSItems (AItems : PSItem);
  261.       dispose a chain of TSItems
  262.  
  263.       function  ReadSItems (var S : TStream) : PSItem;
  264.       reads strings from a pick list
  265.  
  266.       procedure WriteSItems (var S : TStream; Items : PSItem);
  267.       writes strings to a pick list
  268.  
  269.       function  MaxItemStrLen (AItems : PSItem) : integer;
  270.       returns the maximum length of the strings in a pick list
  271.  
  272.       function  SItemsLen (S : PSItem) : integer;
  273.       returns the cumulative length of the strings in a pick list
  274.  
  275.  
  276. ABBREVIATING STRING FIELDS
  277. ══════════════════════════
  278.  
  279.     String fields can now be abbreviated with the '`' character (the
  280.     backward apostrophe) so that long strings don't take up so much
  281.     space on the screen.  While editing, users can scroll within the
  282.     field.  Example:
  283.  
  284.       ' ssssssssssssssssssss`ssssssssssssssssssss| ww,www '
  285.  
  286.     This will be displayed like this:
  287.  
  288.       ' International Busin^|  1,024 '
  289.  
  290.  
  291.  
  292.  
  293.  
  294. tvDMX AUXILIARY VIEWS
  295. ═════════════════════
  296.  
  297.     tvDMX versions prior to 2.0 came with only one view to display the
  298.     titles or field names above the scroller.  Since version 2.0 made
  299.     wide data editors easier to produce, the same needed to be done for
  300.     TDmxLabel objects --so several derivations were created.
  301.  
  302.                                ┌─────────────┐
  303.                                │   TObject   │
  304.                                └──────┬──────┘
  305.                                ┌──────┴──────┐
  306.                                │    TView    │
  307.                                └──────┬──────┘
  308.                                       │
  309.                             ┌─────────┴─────────┐
  310.                             │     TDmxLink      │
  311.                             │   (unit tvDMX)    │
  312.                             └─────────┬─────────┘
  313.                                       │
  314.                          ┌────────────┴────────────┐
  315.                ┌─────────┴─────────┐     ┌─────────┴─────────┐
  316.                │   TDmxExpLabels   │     │    TDmxRecInd     │
  317.                │   (unit tvDMX)    │     │   (unit tvDMX)    │
  318.                └─────────┬─────────┘     └─────────┬─────────┘
  319.                          │               ┌─────────┴─────────┐
  320.                          │               │   TDmxExpRecInd   │
  321.                          │               │  (unit tvDMXBUF)  │
  322.                          │               └───────────────────┘
  323.             ┌────────────┴──────────┬───────────────────────┐
  324.             │                       │                       │
  325.   ┌─────────┴─────────┐   ┌─────────┴─────────┐   ┌─────────┴─────────┐
  326.   │    TDmxLabels     │   │    TDmxFLabels    │   │    TDmxMLabels    │
  327.   │   (unit tvDMX)    │   │   (unit tvDMX)    │   │   (unit tvDMX)    │
  328.   └───────────────────┘   └───────────────────┘   └───────────────────┘
  329.  
  330.  
  331.                                      ...continued on next page
  332.  
  333. tvDMX AUXILIARY VIEWS (continued)
  334. ═════════════════════
  335.  
  336.     Note:  Examples of New(P) would be used as functions, not as procedures.
  337.  
  338.   TDmxExtLabels    =  OBJECT (TDmxLink)
  339.     Descendant of TDmxLink, and parent to TDmxLabels that displays the
  340.     labels line on the first line of the window.  Its constructor is given
  341.     a pointer to the text of the labels line.
  342.  
  343.     Example:  New (PDmxExtLabels, Init (sizeof(LblArr), @LblArr, Bounds));
  344.  
  345.  
  346.   TDmxLabels    =  OBJECT (TDmxExtLabels)
  347.     Default tvDMX labels object.  Its constructor is given a pointer to
  348.     the string for the field labels.
  349.  
  350.     Example:  New (PDmxLabels, Init (@LabelStr, Bounds));
  351.  
  352.  
  353.   TDmxFLabels    =  OBJECT (TDmxExtLabels)
  354.     Alternative to TDmxLabels with a constructor that is given the actual
  355.     string itself for the text of the labels line.
  356.  
  357.     Example:  New (PDmxFLabels, Init (' Name    ID  SSN  ', Bounds));
  358.  
  359.  
  360.   TDmxMLabels    =  OBJECT (TDmxExtLabels)
  361.     Can be used to display DMX labels that must be longer than 255
  362.     characters, but is more convenient to set up than TDmxExtLabels.
  363.  
  364.     Example:  New (PDmxMLabels, Init (
  365.                          NewSItem ('Name            ',
  366.                          NewSItem ('ID      SSN          ',
  367.                          NewSItem ('Balance       ',
  368.                          nil))),
  369.                        Bounds));
  370.  
  371.     A working example of TDmxMLabels is demonstrated in WIDESHOP.PAS.
  372.  
  373.  
  374.